文档测试

概述

文档测试是 Rust 中一个非常强大的功能，它允许你在代码的注释中编写测试用例。这些测试用例不仅可以帮助你验证代码的正确性，还可以作为代码文档的一部分，帮助其他开发者理解你的代码。

为什么需要文档测试？

1. 代码即文档：文档测试使得代码和文档紧密结合，确保文档始终与代码同步。
2. 自动化测试：文档中的代码示例可以自动运行，确保示例代码始终是正确的。
3. 提高代码质量：通过编写文档测试，你可以发现代码中的潜在问题，提高代码的健壮性。

如何编写文档测试

基本语法

文档测试的基本语法非常简单。你只需要在代码注释中使用 /// 或 //! 来编写文档，并在文档中包含代码示例。Rust 会自动将这些代码示例提取出来并运行。

/// 这是一个简单的加法函数
///
/// # Examples
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

运行文档测试

要运行文档测试，你可以使用 cargo test 命令。Cargo 会自动检测并运行所有文档测试。

cargo test

处理错误和输出

文档测试中的代码示例可以包含错误处理和输出。你可以使用 assert!、assert_eq! 等宏来验证代码的正确性。

/// 这是一个除法函数
///
/// # Examples
///
/// ```
/// let result = divide(10, 2);
/// assert_eq!(result, 5);
/// ```
///
/// # Panics
///
/// 如果除数为零，函数会 panic。
///
/// ```rust,should_panic
/// // 这个测试应该会 panic
/// divide(10, 0);
/// ```
pub fn divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("除数不能为零");
    }
    a / b
}

隐藏代码

有时候，你可能希望在文档中隐藏某些代码，但仍然希望这些代码在测试时运行。你可以使用 # 来隐藏代码。

/// 这是一个计算平方的函数
///
/// # Examples
///
/// ```
/// # fn main() {
/// let result = square(4);
/// assert_eq!(result, 16);
/// # }
/// ```
pub fn square(x: i32) -> i32 {
    x * x
}

实践练习

练习 1：编写一个简单的文档测试

编写一个函数 multiply，接受两个整数并返回它们的乘积。为这个函数编写文档测试，确保测试通过。

/// 这是一个乘法函数
///
/// # Examples
///
/// ```
/// let result = multiply(3, 4);
/// assert_eq!(result, 12);
/// ```
pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

练习 2：处理错误

编写一个函数 subtract，接受两个整数并返回它们的差。如果第一个数小于第二个数，函数应该 panic。为这个函数编写文档测试，确保测试通过。

/// 这是一个减法函数
///
/// # Examples
///
/// ```
/// let result = subtract(10, 3);
/// assert_eq!(result, 7);
/// ```
///
/// # Panics
///
/// 如果第一个数小于第二个数，函数会 panic。
///
/// ```rust,should_panic
/// // 这个测试应该会 panic
/// subtract(3, 10);
/// ```
pub fn subtract(a: i32, b: i32) -> i32 {
    if a < b {
        panic!("第一个数不能小于第二个数");
    }
    a - b
}

总结

文档测试是 Rust 中一个非常有用的功能，它不仅可以帮助你编写更好的代码，还可以提高代码的可读性和可维护性。通过在文档中编写测试用例，你可以确保代码示例始终是正确的，并且文档始终与代码同步。

希望这篇教程能帮助你更好地理解和使用 Rust 中的文档测试功能。如果你有任何问题或建议，欢迎在评论区留言。